home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk67 / vlt3656 / docs / rexxarplib.doc < prev    next >
Text File  |  1995-03-19  |  8KB  |  198 lines
  1.  
  2.     RexxArpLib.Library documentation
  3.     ================================
  4.  
  5.     Okay, this is the beginning of a REXX interface to the ARP
  6. library. Only a few functions sofar. One is the famous Heath file requester,
  7. another is a simple combination string/boolean requester that does
  8. auto-everything. All you have to do is specify the strings you want it
  9. to display... Then there are environment variable things, and a simple
  10. message window you can keep hanging around.
  11.  
  12. getfile
  13. =======
  14.  
  15.     Calling sequence:
  16.  
  17.     result = getfile(x, y, pathname, filename, hailstring, publicscreen)
  18.  
  19.     x            = x coordinate of top-left corner of requester.
  20.     y            = y coordinate of top-left corner of requester.
  21.     pathname     = Default path name, first path name to be searched.
  22.         filename     = Default file name.
  23.         hailstring   = User instruction string.
  24.         result       = The selected path/file name
  25.         publicscreen = Name of a public screen (optional).
  26.  
  27.     All arguments are optional, but the order is fixed. Therefore if only
  28. the second or third argument is specified, it needs to be prefixed by
  29. sufficient commas.
  30.     The selected path concatenated with the selected file name are
  31. returned as 'result'. Notice, that the result is not necessarily an existing
  32. file. It is up to the user to ascertain that the result is suitable for his
  33. purposes. If the user hits "CANCEL", the result is an empty string. Notice
  34. that another way the result comes out to be empty is when the user leaves the
  35. requester hitting "OKAY" when both the path and file string gadgets are
  36. empty.
  37.     If 'publicscreen' is specified, the function will try to find the screen
  38. of that name. If it is set up properly, the requester will open on that 
  39. screen. If not, the requester will appear on the Workbench. The mechanism that
  40. is currently used for this is subject to change.
  41.  
  42. request
  43. =======
  44.  
  45.     Calling sequence:
  46.  
  47.     result = request(x, y, prompts, string, okaytext, canceltext, publicscreen)
  48.  
  49.     x             = x coordinate of top-left corner of requester.
  50.     y             = y coordinate of top-left corner of requester.
  51.         prompts       = A string which will be displayed above any gadgets.
  52.                         Any embedded '\' characters will be treated as a line
  53.                         break.
  54.         string        = The default string to be displayed in a string gadget.
  55.                         If omitted, no string gadget will be provided.
  56.     okaytext      = The text to be used for an Okay gadget.
  57.                     If omitted, no okay gadget will be provided.
  58.     canceltext    = The text to be used for a Cancel gadget.
  59.                     If omitted, no cancel gadget will be provided.
  60.         publicscreen  = Name of a public screen (optional).
  61.  
  62.     All arguments are optional, but the order is fixed. Therefore if
  63. only the second or third argument is specified, it needs to be prefixed by
  64. sufficient commas.
  65.     If a string gadget is present, but no okay gadget, the string
  66. will be returned after modification by the user in result when the user
  67. hits <return>.
  68.     If both a string gadget and an okay gadget are present, the string
  69. will be returned in result only when the user clicks on the okay gadget.
  70.     If no string gadget is present, clicking of the okay gadget (if 
  71. present) will cause the return in result of the string "OKAY".
  72.     In any case, if the user clicks either the cancel gadget or the
  73. close gadget, an empty string will be returned. Notice that another way the
  74. result comes out to be empty is when the user leaves the requester hitting
  75. "OKAY" when the string gadget is empty.
  76.     If 'publicscreen' is specified, the function will try to find the screen
  77. of that name. If it is set up properly, the requester will open on that 
  78. screen. If not, the requester will appear on the Workbench. The mechanism that
  79. is currently used for this is subject to change.
  80.  
  81. postmsg
  82. =======
  83.  
  84.     This function sets up a window with text. It returns immediately to
  85. the caller. Subsequent calls will erase lines and fill them with new text.
  86. If a line has zero length, the line will NOT be erased. This has the advantage
  87. that you can change the text in a line without redisplaying text in another
  88. line. It has the disadvantage that in order to erase lines, you have to
  89. specify at least a single space for each line you want to erase.
  90. The window will remain open, until a call is made with too few arguments. 
  91. This is NOT a reentrant function: there is only one window pointer, and
  92. subsequent calls by ANY REXX process will affect the window.
  93.  
  94.     Calling sequence:
  95.  
  96.     result = postmsg(x, y, strings, publicscreen)
  97.  
  98.     x             = x coordinate of top-left corner of requester.
  99.     y             = y coordinate of top-left corner of requester.
  100.         string        = A string which will be displayed above any gadgets.
  101.                         Any embedded '\' characters will be treated as a line
  102.                         break.
  103.     result        = 1 for success, 0 otherwise.
  104.         publicscreen  = Name of a public screen (optional).
  105.  
  106.     All arguments are optional, but the order is fixed. Therefore if
  107. only the second or third argument is specified, it needs to be prefixed by
  108. sufficient commas.
  109.     Examples:
  110.        Postmsg(50, 50, "This is line 1\This is line 2")
  111. will cause a window to appear with two lines of text. A subsequent call
  112.        Postmsg(50, 50, "\This is a new line 2")
  113. will cause the second line of the window to be replaced by the new text. The
  114. construct:
  115.        PostMsg(50, 50, " \")
  116. will erase the first line but leave the second one alone (notice the space).
  117.     If too few arguments are specified, this function will cause the
  118. window to be closed.
  119.     If 'publicscreen' is specified, the function will try to find the screen
  120. of that name. If it is set up properly, the requester will open on that 
  121. screen. If not, the requester will appear on the Workbench. The mechanism that
  122. is currently used for this is subject to change.
  123.  
  124. getenv
  125. ======
  126.  
  127.     Calling sequence:
  128.  
  129.     result = getenv(variable)
  130.  
  131.     variable   = Environment variable.
  132.         result     = The value of the environment variable.
  133.  
  134.     This function gets the value of an environment variable. If the
  135. variable does not exist, an empty string will be returned.
  136.  
  137. setenv
  138. ======
  139.  
  140.     Calling sequence:
  141.  
  142.     result = setenv(variable, valuestring)
  143.  
  144.     variable    = Environment variable.
  145.     valuestring = The new value for the environment variable.
  146.         result      = Always 1.
  147.  
  148.     This function (creates and) sets the environment variable to a
  149. a (new) value. If 'valuestring' is missing, the function will remove the
  150. environment variable.
  151.  
  152. screentoback, screentofront
  153. ===========================
  154.  
  155.     These functions depth arrange screens. If no argument is specified,
  156. the screen operated on is the Workbench screen. If the name of a public screen
  157. is specified, it will be affected.
  158.  
  159.     Calling sequence:
  160.  
  161.     result = screentoback(publicscreen)
  162.     result = screentofront(publicscreen)
  163.  
  164.         publicscreen  = Name of a public screen (optional).
  165.  
  166.     The argument is optional. If 'publicscreen' is specified, the function
  167. will try to find the screen of that name. If it is set up properly, the screen
  168. will be moved to the back/front. If not, the function will operate on the
  169. Workbench screen. The mechanism that is currently used for this is subject to
  170. change.
  171.  
  172. screenrows, screencols, screenlace
  173. ==================================
  174.  
  175.     These functions retrieve info about screens. If no argument is
  176. specified, the screen operated on is the Workbench screen. If the name of a
  177. public screen is specified, it will be used.
  178.  
  179.     Calling sequence:
  180.  
  181.     result = screenrows(publicscreen)     /* return number of rows */
  182.     result = screencols(publicscreen)     /* return number of columns */
  183.     result = screenlace(publicscreen)     /* return interlace */
  184.  
  185.         publicscreen  = Name of a public screen (optional).
  186.  
  187.     These functions retrieve the number of rows and columns in pixels.
  188. The function screenlace() returns 0 if the screen is not interlaced, and 1
  189. if it is. The function returns -1 if the information could not be found.
  190.     The argument is optional.  If 'publicscreen' is specified, the function
  191. will try to find the screen of that name. If it is set up properly, information
  192. about the screen will be returned. If not, the function will operate on the
  193. Workbench screen. The mechanism that is currently used for this is subject to
  194. change.
  195.  
  196.  
  197.     Willy.
  198.